

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Playdoh Reference &mdash; Playdoh v0.3.1 documentation</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '0.3.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="Playdoh v0.3.1 documentation" href="index.html" />
    <link rel="prev" title="Example: resources" href="examples-resources.html" /> 
  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="examples-resources.html" title="Example: resources"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">Playdoh v0.3.1 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="playdoh-reference">
<span id="reference"></span><h1>Playdoh Reference<a class="headerlink" href="#playdoh-reference" title="Permalink to this headline">¶</a></h1>
<p>This page details the usage of the functions and classes of Playdoh.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#playdoh"><em>Playdoh User Guide</em></a>.</p>
</div>
<div class="section" id="main-functions-and-classes">
<h2>Main functions and classes<a class="headerlink" href="#main-functions-and-classes" title="Permalink to this headline">¶</a></h2>
<p>This section details the usage of the Playdoh functions that
are used to launch computations.</p>
<div class="section" id="independent-parallel-problems">
<span id="ref-independent"></span><h3>Independent parallel problems<a class="headerlink" href="#independent-parallel-problems" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt id="playdoh.map">
<tt class="descclassname">playdoh.</tt><tt class="descname">map</tt><big>(</big><em>fun</em>, <em>**kwds</em><big>)</big><a class="headerlink" href="#playdoh.map" title="Permalink to this definition">¶</a></dt>
<dd><p>Parallel version of the built-in <tt class="docutils literal"><span class="pre">map</span></tt> function.
Executes the function <tt class="docutils literal"><span class="pre">fun</span></tt> with the arguments <tt class="docutils literal"><span class="pre">*argss</span></tt> and
keyword arguments <tt class="docutils literal"><span class="pre">**kwdss</span></tt> across CPUs on one or several computers.
Each argument and keyword argument is a list with the arguments
of every job.
This function returns the result as a list, one item per job.
If an exception occurs within the function, <a class="reference internal" href="#playdoh.map" title="playdoh.map"><tt class="xref py py-func docutils literal"><span class="pre">map()</span></tt></a> returns
the Exception object as a result. This object has an extra attribute,
<tt class="docutils literal"><span class="pre">traceback</span></tt>, which contains the traceback of the exception.</p>
<p>Special keyword arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">cpu=MAXCPU</span></tt></dt>
<dd>Total number of CPUs to distribute the function over.
If <tt class="docutils literal"><span class="pre">machines</span></tt> is not specified or is an empty list,
only CPUs on the local computer will be used.
The total number of CPUs is obtained with the global
variable <tt class="docutils literal"><span class="pre">MAXCPU</span></tt>. By default, all CPUs on the machine
are used.</dd>
<dt><tt class="docutils literal"><span class="pre">gpu=0</span></tt></dt>
<dd><p class="first">If the function loads CUDA code using the PyCUDA package,
Playdoh is able to distribute it across GPUs on one or
several machines. In this case, <tt class="docutils literal"><span class="pre">gpu</span></tt> is the total
number of GPUs to use and works the same way as <tt class="docutils literal"><span class="pre">cpu</span></tt>.</p>
<div class="admonition-see-also last admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide <a class="reference internal" href="playdoh.html#gpu"><em>Using GPUs</em></a>.</p>
</div>
</dd>
<dt><tt class="docutils literal"><span class="pre">machines=[]</span></tt></dt>
<dd>The list of computers to distribute the function over.
Items can be either IP addresses as strings, or tuples
<tt class="docutils literal"><span class="pre">('IP',</span> <span class="pre">port)</span></tt> where <tt class="docutils literal"><span class="pre">port</span></tt> is an integer giving
the port over which the Playdoh server is listening
on the remote computer. The default port is obtained
with the global variable <tt class="docutils literal"><span class="pre">DEFAULT_PORT</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">allocation=None</span></tt></dt>
<dd><p class="first">Resource allocation is normally done automatically assuming
that all CPUs are equivalent. However, it can also be done
manually by specifying the number of CPUs to use on every
computer. It is done with the <a class="reference internal" href="#playdoh.allocate" title="playdoh.allocate"><tt class="xref py py-func docutils literal"><span class="pre">allocate()</span></tt></a> function.</p>
<div class="admonition-see-also last admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#allocation"><em>Resource allocation</em></a>.</p>
</div>
</dd>
<dt><tt class="docutils literal"><span class="pre">shared_data={}</span></tt></dt>
<dd><p class="first">Large data objects (NumPy arrays) can be shared across CPUs
running on the same
computer, but they must be read-only. The <tt class="docutils literal"><span class="pre">shared_data</span></tt>
argument is a
dictionary: keys are variable names and values are large
NumPy arrays that should be stored in shared memory
on every computer if possible.</p>
<div class="admonition-see-also last admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#shared-data"><em>Shared data</em></a>.</p>
</div>
</dd>
<dt><tt class="docutils literal"><span class="pre">codedependencies=[]</span></tt></dt>
<dd><p class="first">If the function to distribute uses external Python modules,
these modules must be transported to every machine along
with the function code. The <tt class="docutils literal"><span class="pre">codedependencies</span></tt> argument
contains the list of these modules&#8217; pathnames relatively
to the directory where the function&#8217;s module is defined.</p>
<div class="admonition-see-also last admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#code-transport"><em>Code transport</em></a>.</p>
</div>
</dd>
</dl>
</dd></dl>

<dl class="function">
<dt id="playdoh.map_async">
<tt class="descclassname">playdoh.</tt><tt class="descname">map_async</tt><big>(</big><em>fun</em>, <em>**kwds</em><big>)</big><a class="headerlink" href="#playdoh.map_async" title="Permalink to this definition">¶</a></dt>
<dd><p>Asynchronous version of <tt class="docutils literal"><span class="pre">map</span></tt>. Return a <a class="reference internal" href="#playdoh.JobRun" title="playdoh.JobRun"><tt class="xref py py-class docutils literal"><span class="pre">JobRun</span></tt></a> object
which allows to poll the jobs&#8217;
status asynchronously and retrieve the results later.</p>
<p>The <a class="reference internal" href="#playdoh.map" title="playdoh.map"><tt class="xref py py-func docutils literal"><span class="pre">map()</span></tt></a> function is equivalent to <tt class="docutils literal"><span class="pre">map_async(...).get_results()</span></tt>.</p>
</dd></dl>

<dl class="class">
<dt id="playdoh.JobRun">
<em class="property">class </em><tt class="descclassname">playdoh.</tt><tt class="descname">JobRun</tt><a class="headerlink" href="#playdoh.JobRun" title="Permalink to this definition">¶</a></dt>
<dd><p>Contains information about a parallel map that has been launched
by the <tt class="docutils literal"><span class="pre">map_async</span></tt> function.</p>
<p>Methods:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">get_status()</span></tt></dt>
<dd>Returns the current status of the jobs.</dd>
<dt><tt class="docutils literal"><span class="pre">get_result(jobids=None)</span></tt></dt>
<dd>Returns the result. Blocks until the jobs have finished.
You can specify jobids to retrieve only some of the results,
in that case it must
be a list of job identifiers.</dd>
</dl>
</dd></dl>

<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#guide-independent"><em>Independent parallel problems</em></a>.</p>
</div>
</div>
<div class="section" id="optimization">
<span id="ref-optimization"></span><h3>Optimization<a class="headerlink" href="#optimization" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt id="playdoh.minimize">
<tt class="descclassname">playdoh.</tt><tt class="descname">minimize</tt><big>(</big><em>fun</em>, <em>**kwds</em><big>)</big><a class="headerlink" href="#playdoh.minimize" title="Permalink to this definition">¶</a></dt>
<dd><p>Minimize a fitness function in parallel across CPUs on one or several
computers.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">fitness</span></tt></dt>
<dd><p class="first">The first argument is the fitness function. There are four
possibilities:
it can be a Python function or a Python class (deriving from
<a class="reference internal" href="#playdoh.Fitness" title="playdoh.Fitness"><tt class="xref py py-class docutils literal"><span class="pre">Fitness</span></tt></a>).
It can also accept either keyword named arguments (like
<tt class="docutils literal"><span class="pre">fitness(**kwds)</span></tt>)
or a <tt class="docutils literal"><span class="pre">DxN</span></tt> matrix (like <tt class="docutils literal"><span class="pre">fitness(X)</span></tt>) where there are <tt class="docutils literal"><span class="pre">D</span></tt>
dimensions in the
parameter space and <tt class="docutils literal"><span class="pre">N</span></tt> particles.</p>
<p>Using a class rather than a function allows to implement an
initialization step
at the beginning of the optimization. See the reference for
<a class="reference internal" href="#playdoh.Fitness" title="playdoh.Fitness"><tt class="xref py py-class docutils literal"><span class="pre">Fitness</span></tt></a>.</p>
<p>If the fitness is a simple keyword-like Python function, it must have
the right keyword arguments.
For example, if there are two parameters <tt class="docutils literal"><span class="pre">x</span></tt> and <tt class="docutils literal"><span class="pre">y</span></tt> to optimize,
the fitness function
must be like <tt class="docutils literal"><span class="pre">def</span> <span class="pre">fitness(x,y):</span></tt>. If it&#8217;s a matrix-like function,
it must accept a single argument
which is a matrix: <tt class="docutils literal"><span class="pre">def</span> <span class="pre">fitness(X):</span></tt>.</p>
<p>Fitness functions can also accept static arguments, given in the
<a class="reference internal" href="#playdoh.minimize" title="playdoh.minimize"><tt class="xref py py-func docutils literal"><span class="pre">minimize()</span></tt></a> functions
and alike with the <tt class="docutils literal"><span class="pre">args</span></tt> and <tt class="docutils literal"><span class="pre">kwds</span></tt> parameters (see below).</p>
<p>In addition, the fitness function can accept several special keyword
arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">dimension</span></tt></dt>
<dd>The dimension of the state space, or the number of optimizing
parameters</dd>
<dt><tt class="docutils literal"><span class="pre">popsize</span></tt></dt>
<dd>The total population size for each group across all nodes.</dd>
<dt><tt class="docutils literal"><span class="pre">subpopsize</span></tt></dt>
<dd>The population size for each group on this node.</dd>
<dt><tt class="docutils literal"><span class="pre">groups</span></tt></dt>
<dd>The number of groups.</dd>
<dt><tt class="docutils literal"><span class="pre">nodesize</span></tt></dt>
<dd>The population size for all groups on this node.</dd>
<dt><tt class="docutils literal"><span class="pre">nodecount</span></tt></dt>
<dd>The number of nodes used for this optimization.</dd>
<dt><tt class="docutils literal"><span class="pre">shared_data</span></tt></dt>
<dd>The dictionary with shared data.</dd>
<dt><tt class="docutils literal"><span class="pre">unit_type</span></tt></dt>
<dd>The unit type, <tt class="docutils literal"><span class="pre">CPU</span></tt> or <tt class="docutils literal"><span class="pre">GPU</span></tt>.</dd>
</dl>
<p class="last">For example, use the following syntax to retrieve within the function
the shared data dictionary and the size of the population on the
current node:
<tt class="docutils literal"><span class="pre">def</span> <span class="pre">fitness(X,</span> <span class="pre">shared_data,</span> <span class="pre">nodesize):</span></tt>.</p>
</dd>
<dt><tt class="docutils literal"><span class="pre">popsize=100</span></tt></dt>
<dd>Size of the population. If there are several groups, it is the size
of the population for every group.</dd>
<dt><tt class="docutils literal"><span class="pre">maxiter=5</span></tt></dt>
<dd>Maximum number of iterations.</dd>
<dt><tt class="docutils literal"><span class="pre">algorithm=PSO</span></tt></dt>
<dd>Optimization algorithm. For now, it can be <a class="reference internal" href="#playdoh.PSO" title="playdoh.PSO"><tt class="xref py py-class docutils literal"><span class="pre">PSO</span></tt></a>, <a class="reference internal" href="#playdoh.GA" title="playdoh.GA"><tt class="xref py py-class docutils literal"><span class="pre">GA</span></tt></a>
or <a class="reference internal" href="#playdoh.CMAES" title="playdoh.CMAES"><tt class="xref py py-class docutils literal"><span class="pre">CMAES</span></tt></a>.</dd>
<dt><tt class="docutils literal"><span class="pre">allocation=None</span></tt></dt>
<dd><p class="first"><a class="reference internal" href="#playdoh.Allocation" title="playdoh.Allocation"><tt class="xref py py-class docutils literal"><span class="pre">Allocation</span></tt></a> object.</p>
<div class="admonition-see-also last admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#allocation"><em>Resource allocation</em></a>.</p>
</div>
</dd>
<dt><tt class="docutils literal"><span class="pre">shared_data={}</span></tt></dt>
<dd><p class="first">Dictionary containing shared data between CPUs on a same computer.</p>
<div class="admonition-see-also last admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#shared-data"><em>Shared data</em></a>.</p>
</div>
</dd>
<dt><tt class="docutils literal"><span class="pre">groups=1</span></tt></dt>
<dd><p class="first">Number of groups. Allows to optimize independently several populations
by using a single vectorized call to the fitness function at every
iteration.</p>
<div class="admonition-see-also last admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#groups"><em>Optimization groups</em></a>.</p>
</div>
</dd>
<dt><tt class="docutils literal"><span class="pre">cpu=MAXCPU</span></tt></dt>
<dd>Total number of CPUs to use.</dd>
<dt><tt class="docutils literal"><span class="pre">gpu=0</span></tt></dt>
<dd>If the fitness function loads CUDA code using the PyCUDA package,
several
GPUs can be used. In this case, <tt class="docutils literal"><span class="pre">gpu</span></tt> is the total number of GPUs.</dd>
<dt><tt class="docutils literal"><span class="pre">codedependencies=[]</span></tt></dt>
<dd><p class="first">List of dependent modules.</p>
<div class="admonition-see-also last admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#code-transport"><em>Code transport</em></a>.</p>
</div>
</dd>
<dt><tt class="docutils literal"><span class="pre">optparams={}</span></tt></dt>
<dd>Optimization algorithm parameters. It is a dictionary: keys are
parameter names,
values are parameter values or lists of parameters (one value per
group).
This argument is specific to the optimization
algorithm used. See <a class="reference internal" href="#playdoh.PSO" title="playdoh.PSO"><tt class="xref py py-class docutils literal"><span class="pre">PSO</span></tt></a>, <a class="reference internal" href="#playdoh.GA" title="playdoh.GA"><tt class="xref py py-class docutils literal"><span class="pre">GA</span></tt></a>, <a class="reference internal" href="#playdoh.CMAES" title="playdoh.CMAES"><tt class="xref py py-class docutils literal"><span class="pre">CMAES</span></tt></a>.</dd>
<dt><tt class="docutils literal"><span class="pre">machines=[]</span></tt></dt>
<dd>List of machines to distribute the optimization over.</dd>
<dt><tt class="docutils literal"><span class="pre">scaling=None</span></tt></dt>
<dd>Specify the scaling used for the parameters during the optimization.
It can be <tt class="xref docutils literal"><span class="pre">None</span></tt> or <tt class="docutils literal"><span class="pre">'mapminmax'</span></tt>. It is <tt class="xref docutils literal"><span class="pre">None</span></tt>
by default (no scaling), and <tt class="docutils literal"><span class="pre">mapminmax</span></tt> by default for the
CMAES algorithm.</dd>
<dt><tt class="docutils literal"><span class="pre">returninfo=False</span></tt></dt>
<dd>Boolean specifying whether information about the optimization
should be returned with the results.</dd>
<dt><tt class="docutils literal"><span class="pre">args=()</span></tt></dt>
<dd>With fitness functions, arguments of the fitness function in addition
of the
optimizing parameters.
With fitness classes, arguments of the <tt class="docutils literal"><span class="pre">initialize</span></tt> method of the
<a class="reference internal" href="#playdoh.Fitness" title="playdoh.Fitness"><tt class="xref py py-class docutils literal"><span class="pre">Fitness</span></tt></a> class.
When using a fitness keyword-like function, the arguments must be
before the optimizing
parameters, i.e. like <tt class="docutils literal"><span class="pre">def</span> <span class="pre">fitness(arg1,</span> <span class="pre">arg2,</span> <span class="pre">x1,</span> <span class="pre">x2):</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">kwds={}</span></tt></dt>
<dd>With fitness functions, keyword arguments of the fitness function in
addition of the
optimizing parameters.
With fitness classes, keyword arguments of the <tt class="docutils literal"><span class="pre">initialize</span></tt> method
of the <a class="reference internal" href="#playdoh.Fitness" title="playdoh.Fitness"><tt class="xref py py-class docutils literal"><span class="pre">Fitness</span></tt></a> class.</dd>
<dt><tt class="docutils literal"><span class="pre">bounds=None</span></tt></dt>
<dd>Used with array-like fitness functions only.
This argument is a Dx2 NumPy array with the boundaries of the parameter
space.
The first column contains the minimum values acceptable for
the parameters
(or -inf), the second column contains the maximum values
(or +inf).</dd>
<dt><tt class="docutils literal"><span class="pre">initrange=None</span></tt></dt>
<dd>Used with array-like fitness functions only.
This argument is a Dx2 NumPy array with the initial range in which
the parameters should be sampled at the algorithm initialization.</dd>
<dt><tt class="docutils literal"><span class="pre">**params</span></tt></dt>
<dd>Used with keyword-like fitness functions only.
For every parameter &lt;paramname&gt;, the initial sampling interval
can be specified with the keyword <tt class="docutils literal"><span class="pre">&lt;paramname&gt;_initrange</span></tt> which is
a tuple with two values <tt class="docutils literal"><span class="pre">(min,max)</span></tt>.
The boundaries can be specified with the keyword <tt class="docutils literal"><span class="pre">&lt;paramname&gt;_bound</span></tt>
which is a tuple with two values <tt class="docutils literal"><span class="pre">(min,max)</span></tt>.
For example, if there is a single parameter in the fitness function,
<tt class="docutils literal"><span class="pre">def</span> <span class="pre">fitness(x):</span></tt>,
use the following syntax:
<tt class="docutils literal"><span class="pre">minimize(...,</span> <span class="pre">x_initrange=(-1,1),</span> <span class="pre">x_bounds=(-10,10))</span></tt>.</dd>
</dl>
<p>Return an <a class="reference internal" href="#playdoh.OptimizationResult" title="playdoh.OptimizationResult"><tt class="xref py py-class docutils literal"><span class="pre">OptimizationResult</span></tt></a> object with the following attributes:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">best_pos</span></tt></dt>
<dd>Minimizing position found by the algorithm. For array-like fitness
functions,
it is a single vector if there is one group, or a list of vectors.
For keyword-like fitness functions, it is a dictionary
where keys are parameter names and values are numeric values. If there
are several groups,
it is a list of dictionaries.</dd>
<dt><tt class="docutils literal"><span class="pre">best_fit</span></tt></dt>
<dd>The value of the fitness function for the best positions. It is a
single value if
there is one group, or it is a list if there are several groups.</dd>
<dt><tt class="docutils literal"><span class="pre">info</span></tt></dt>
<dd><p class="first">A dictionary containing various information about the optimization.</p>
<div class="admonition-see-also last admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#optinfo"><em>Optimization information</em></a>.</p>
</div>
</dd>
</dl>
</dd></dl>

<dl class="function">
<dt id="playdoh.maximize">
<tt class="descclassname">playdoh.</tt><tt class="descname">maximize</tt><big>(</big><em>fun</em>, <em>**kwds</em><big>)</big><a class="headerlink" href="#playdoh.maximize" title="Permalink to this definition">¶</a></dt>
<dd><p>Maximize a fitness function in parallel across CPUs on one or several
computers. Completely analogous to <a class="reference internal" href="#playdoh.minimize" title="playdoh.minimize"><tt class="xref py py-func docutils literal"><span class="pre">minimize()</span></tt></a>.</p>
</dd></dl>

<dl class="function">
<dt id="playdoh.minimize_async">
<tt class="descclassname">playdoh.</tt><tt class="descname">minimize_async</tt><big>(</big><em>fun</em>, <em>**kwds</em><big>)</big><a class="headerlink" href="#playdoh.minimize_async" title="Permalink to this definition">¶</a></dt>
<dd><p>Asynchronous version of <a class="reference internal" href="#playdoh.minimize" title="playdoh.minimize"><tt class="xref py py-func docutils literal"><span class="pre">minimize()</span></tt></a>. Returns an
<a class="reference internal" href="#playdoh.OptimizationRun" title="playdoh.OptimizationRun"><tt class="xref py py-class docutils literal"><span class="pre">OptimizationRun</span></tt></a> object.</p>
</dd></dl>

<dl class="function">
<dt id="playdoh.maximize_async">
<tt class="descclassname">playdoh.</tt><tt class="descname">maximize_async</tt><big>(</big><em>fun</em>, <em>**kwds</em><big>)</big><a class="headerlink" href="#playdoh.maximize_async" title="Permalink to this definition">¶</a></dt>
<dd><p>Asynchronous version of <a class="reference internal" href="#playdoh.maximize" title="playdoh.maximize"><tt class="xref py py-func docutils literal"><span class="pre">maximize()</span></tt></a>. Returns an
<a class="reference internal" href="#playdoh.OptimizationRun" title="playdoh.OptimizationRun"><tt class="xref py py-class docutils literal"><span class="pre">OptimizationRun</span></tt></a> object.</p>
</dd></dl>

<dl class="function">
<dt id="playdoh.print_table">
<tt class="descclassname">playdoh.</tt><tt class="descname">print_table</tt><big>(</big><em>results</em>, <em>precision=4</em>, <em>colwidth=16</em><big>)</big><a class="headerlink" href="#playdoh.print_table" title="Permalink to this definition">¶</a></dt>
<dd><p>Displays the results of an optimization in a table.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">results</span></tt></dt>
<dd>The results returned by the <tt class="docutils literal"><span class="pre">minimize</span></tt> of <tt class="docutils literal"><span class="pre">maximize</span></tt> function.</dd>
<dt><tt class="docutils literal"><span class="pre">precision</span> <span class="pre">=</span> <span class="pre">4</span></tt></dt>
<dd>The number of decimals to print for the parameter values.</dd>
<dt><tt class="docutils literal"><span class="pre">colwidth</span> <span class="pre">=</span> <span class="pre">16</span></tt></dt>
<dd>The width of the columns in the table.</dd>
</dl>
</dd></dl>

<dl class="class">
<dt id="playdoh.Fitness">
<em class="property">class </em><tt class="descclassname">playdoh.</tt><tt class="descname">Fitness</tt><a class="headerlink" href="#playdoh.Fitness" title="Permalink to this definition">¶</a></dt>
<dd><p>The base class from which any fitness class must derive.
When using several CPUs or several machines, every node contains
its own instance of this class.
The derived class must implement two methods:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">initialize(self,</span> <span class="pre">*args,</span> <span class="pre">**kwds)</span></tt></dt>
<dd>This method initializes the fitness function at the beginning
of the optimization. The arguments are provided from an optimization
function like <a class="reference internal" href="#playdoh.minimize" title="playdoh.minimize"><tt class="xref py py-func docutils literal"><span class="pre">minimize()</span></tt></a> or <a class="reference internal" href="#playdoh.maximize" title="playdoh.maximize"><tt class="xref py py-func docutils literal"><span class="pre">maximize()</span></tt></a>, with the
parameters <tt class="docutils literal"><span class="pre">args</span></tt> and <tt class="docutils literal"><span class="pre">kwds</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">evaluate(self,</span> <span class="pre">**kwds)</span></tt>.</dt>
<dd>This method evaluates the fitness against particle positions.
For keyword-like fitness functions, <tt class="docutils literal"><span class="pre">kwds</span></tt> is a dictionary where
keys are parameter names, and values are vectors of parameter values.
This method must return a vector with fitness values for all particles.</dd>
</dl>
<p>In addition, several properties are available in this class:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">self.dimension</span></tt></dt>
<dd><dl class="first last docutils">
<dt>The dimension of the state space, or the number of optimizing</dt>
<dd>parameters</dd>
</dl>
</dd>
<dt><tt class="docutils literal"><span class="pre">self.popsize</span></tt></dt>
<dd>The total population size for each group across all nodes.</dd>
<dt><tt class="docutils literal"><span class="pre">self.subpopsize</span></tt></dt>
<dd>The population size for each group on this node.</dd>
<dt><tt class="docutils literal"><span class="pre">self.groups</span></tt></dt>
<dd>The number of groups.</dd>
<dt><tt class="docutils literal"><span class="pre">self.nodesize</span></tt></dt>
<dd>The population size for all groups on this node.</dd>
<dt><tt class="docutils literal"><span class="pre">self.nodecount</span></tt></dt>
<dd>The number of nodes used for this optimization.</dd>
<dt><tt class="docutils literal"><span class="pre">self.shared_data</span></tt></dt>
<dd>The dictionary with shared data.</dd>
<dt><tt class="docutils literal"><span class="pre">self.unit_type</span></tt></dt>
<dd>The unit type, <tt class="docutils literal"><span class="pre">CPU</span></tt> or <tt class="docutils literal"><span class="pre">GPU</span></tt>.</dd>
</dl>
</dd></dl>

<dl class="class">
<dt id="playdoh.PSO">
<em class="property">class </em><tt class="descclassname">playdoh.</tt><tt class="descname">PSO</tt><big>(</big><em>index</em>, <em>nodes</em>, <em>tubes</em>, <em>popsize</em>, <em>subpopsize</em>, <em>nodesize</em>, <em>groups</em>, <em>return_info</em>, <em>maxiter</em>, <em>scaling</em>, <em>parameters</em>, <em>optparams</em><big>)</big><a class="headerlink" href="#playdoh.PSO" title="Permalink to this definition">¶</a></dt>
<dd><p>Particle Swarm Optimization algorithm.
See the
<a class="reference external" href="http://en.wikipedia.org/wiki/Particle_swarm_optimization">wikipedia entry on PSO</a>.</p>
<p>Optimization parameters:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">omega</span></tt></dt>
<dd>The parameter <tt class="docutils literal"><span class="pre">omega</span></tt> is the &#8220;inertial constant&#8221;</dd>
<dt><tt class="docutils literal"><span class="pre">cl</span></tt></dt>
<dd><dl class="first last docutils">
<dt><tt class="docutils literal"><span class="pre">cl</span></tt> is the &#8220;local best&#8221; constant affecting how much</dt>
<dd>the particle&#8217;s personal best position influences its movement.</dd>
</dl>
</dd>
<dt><tt class="docutils literal"><span class="pre">cg</span></tt></dt>
<dd><tt class="docutils literal"><span class="pre">cg</span></tt> is the &#8220;global best&#8221; constant affecting how much the global best
position influences each particle&#8217;s movement.</dd>
</dl>
<p>See the
<a class="reference external" href="http://en.wikipedia.org/wiki/Particle_swarm_optimization">wikipedia entry on PSO</a>
for more details (note that they use <tt class="docutils literal"><span class="pre">c_1</span></tt> and <tt class="docutils literal"><span class="pre">c_2</span></tt> instead of <tt class="docutils literal"><span class="pre">cl</span></tt>
and <tt class="docutils literal"><span class="pre">cg</span></tt>). Reasonable values are (.9, .5, 1.5), but experimentation
with other values is a good idea.</p>
</dd></dl>

<dl class="class">
<dt id="playdoh.CMAES">
<em class="property">class </em><tt class="descclassname">playdoh.</tt><tt class="descname">CMAES</tt><big>(</big><em>index</em>, <em>nodes</em>, <em>tubes</em>, <em>popsize</em>, <em>subpopsize</em>, <em>nodesize</em>, <em>groups</em>, <em>return_info</em>, <em>maxiter</em>, <em>scaling</em>, <em>parameters</em>, <em>optparams</em><big>)</big><a class="headerlink" href="#playdoh.CMAES" title="Permalink to this definition">¶</a></dt>
<dd><p>Covariance Matrix Adaptation Evolution Strategy algorithm
See the
<a class="reference external" href="http://en.wikipedia.org/wiki/CMA-ES">wikipedia entry on CMAES</a>
and also the author&#8217;s website &lt;<a class="reference external" href="http://www.lri.fr/~hansen/cmaesintro.html">http://www.lri.fr/~hansen/cmaesintro.html</a>&gt;`</p>
<p>Optimization parameters:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">proportion_selective</span> <span class="pre">=</span> <span class="pre">0.5</span></tt></dt>
<dd>This parameter (refered to as mu in the CMAES algorithm) is the
proportion (out of 1) of the entire population that is selected and
used to update the generative distribution. (note for different groups
case: this parameter can only have one value, i.e. every group
will have the same value (the first of the list))</dd>
<dt><tt class="docutils literal"><span class="pre">bound_strategy</span> <span class="pre">=</span> <span class="pre">1</span></tt>:</dt>
<dd><p class="first">In the case of a bounded problem, there are two ways to handle the new
generated points which fall outside the boundaries.
(note for different groups case: this parameter can only have one
value, i.e. every group will have the same
value (the first of the list))</p>
<p><tt class="docutils literal"><span class="pre">bound_strategy</span> <span class="pre">=</span> <span class="pre">1</span></tt>. With this strategy, every point outside the
domain is repaired, i.e. it is projected to its nearset possible
value <img class="math" src="_images/math/4205e8d81bf3239c0a98c580d9b6e08693973300.png" alt="x_{repaired}"/>. In other words, components that are
infeasible in <img class="math" src="_images/math/26eeb5258ca5099acf8fe96b2a1049c48c89a5e6.png" alt="x"/> are set to the (closest) boundary value
in <img class="math" src="_images/math/4205e8d81bf3239c0a98c580d9b6e08693973300.png" alt="x_{repaired}"/> The fitness function on the repaired search
points is evaluated and a penalty which depends on the distance to
the repaired solution is added
<img class="math" src="_images/math/28d2dcec2a3e58043f6b56921d57fcd58ac6418e.png" alt="f_{fitness}(x) = f(x_{repaired})+\gamma \|x-x_{repaired}\|^{2}"/>
The repaired solution is disregarded afterwards.</p>
<p class="last"><tt class="docutils literal"><span class="pre">bound_strategy</span> <span class="pre">=</span> <span class="pre">2</span></tt>. With this strategy any infeasible solution x is
resampled until it become feasible. It should be used only if the
optimal solution is not close to the infeasible domain.</p>
</dd>
</dl>
<p>See p.28 of &lt;<a class="reference external" href="http://www.lri.fr/~hansen/cmatutorial.pdf">http://www.lri.fr/~hansen/cmatutorial.pdf</a>&gt; for more details
<tt class="docutils literal"><span class="pre">gamma</span></tt>:</p>
<blockquote>
<tt class="docutils literal"><span class="pre">gamma</span></tt> is the weight <img class="math" src="_images/math/66981fa3920210c6ad8dbe5e968783d5dd7520c3.png" alt="\gamma"/> in the previously introduced
penalty function. (note for different groups case: this parameter can
only have one value, i.e. every group will have the same
value (the first of the list))</blockquote>
</dd></dl>

<dl class="class">
<dt id="playdoh.GA">
<em class="property">class </em><tt class="descclassname">playdoh.</tt><tt class="descname">GA</tt><big>(</big><em>index</em>, <em>nodes</em>, <em>tubes</em>, <em>popsize</em>, <em>subpopsize</em>, <em>nodesize</em>, <em>groups</em>, <em>return_info</em>, <em>maxiter</em>, <em>scaling</em>, <em>parameters</em>, <em>optparams</em><big>)</big><a class="headerlink" href="#playdoh.GA" title="Permalink to this definition">¶</a></dt>
<dd><p>Standard genetic algorithm.
See the
<a class="reference external" href="http://en.wikipedia.org/wiki/Genetic_algorithm">wikipedia entry on GA</a></p>
<p>If more than one worker is used, it works in an island topology, i.e. as a
coarse - grained parallel genetic algorithms which assumes
a population on each of the computer nodes and migration of individuals
among the nodes.</p>
<p>Optimization parameters:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">proportion_parents</span> <span class="pre">=</span> <span class="pre">1</span></tt></dt>
<dd>proportion (out of 1) of the entire population taken
as potential parents.</dd>
<dt><tt class="docutils literal"><span class="pre">migration_time_interval</span> <span class="pre">=</span> <span class="pre">20</span></tt></dt>
<dd>whenever more than one worker is used, it is the number of
iteration at which a migration happens.
(note for different groups case: this parameter can only have
one value, i.e. every group will have the same value
(the first of the list))</dd>
<dt><tt class="docutils literal"><span class="pre">proportion_migration</span> <span class="pre">=</span> <span class="pre">0.2</span></tt></dt>
<dd>proportion (out of 1) of the island population that will migrate to
the next island (the best one) and also the worst that will be
replaced by the best of the previous island. (note for different
groups case: this parameter can only have one value, i.e. every group
will have the same value (the first of the list))</dd>
<dt><tt class="docutils literal"><span class="pre">proportion_xover</span> <span class="pre">=</span> <span class="pre">0.65</span></tt></dt>
<dd>proportion (out of 1) of the entire population which will
undergo a cross over.</dd>
<dt><tt class="docutils literal"><span class="pre">proportion_elite</span> <span class="pre">=</span> <span class="pre">0.05</span></tt></dt>
<dd><p class="first">proportion (out of 1) of the entire population which will be kept
for the next generation based on their best fitness.</p>
<dl class="last docutils">
<dt>The proportion of mutation is automatically set to</dt>
<dd><tt class="docutils literal"><span class="pre">1</span> <span class="pre">-</span> <span class="pre">proportion_xover</span> <span class="pre">-</span> <span class="pre">proportion_elite</span></tt>.</dd>
</dl>
</dd>
<dt><tt class="docutils literal"><span class="pre">func_selection</span> <span class="pre">=</span> <span class="pre">'stoch_uniform'</span></tt></dt>
<dd>This function define the way the parents are chosen
(it is the only one available). It lays out a line in
which each parent corresponds to a section of the line of length
proportional to its scaled value. The algorithm moves along the
line in steps of equal size. At each step, the algorithm allocates
a parent from the section it lands on. The first step is
a uniform random number less than the step size.</dd>
</dl>
<p><tt class="docutils literal"><span class="pre">func_xover</span> <span class="pre">=</span> <span class="pre">'intermediate'</span></tt></p>
<blockquote>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">func_xover</span></tt> specifies the function that performs the crossover.</dt>
<dd>The following ones are available:</dd>
</dl>
<ul>
<li><dl class="first docutils">
<dt><cite>intermediate</cite>: creates children by taking a random weighted average</dt>
<dd><p class="first">of the parents. You can specify the weights by a single parameter,
<tt class="docutils literal"><span class="pre">ratio_xover</span></tt> (which is 0.5 by default). The function creates the
child from parent1 and parent2 using the  following formula:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="n">child</span> <span class="o">=</span> <span class="n">parent1</span> <span class="o">+</span> <span class="n">rand</span> <span class="o">*</span> <span class="n">Ratio</span> <span class="o">*</span> <span class="p">(</span> <span class="n">parent2</span> <span class="o">-</span> <span class="n">parent1</span><span class="p">)</span>
</pre></div>
</div>
</dd>
</dl>
</li>
<li><dl class="first docutils">
<dt><cite>discrete_random</cite>: creates a random binary vector and selects the</dt>
<dd><p class="first last">genes where the vector is a 1 from the first parent, and the gene
where the vector is a 0 from the second parent, and combines the
genes to form the child.</p>
</dd>
</dl>
</li>
<li><p class="first"><cite>one_point</cite>: chooses a random integer n between 1 and ndimensions
and then selects vector entries numbered less than or equal to n
from the first parent. It then Selects vector entries numbered
greater than n from the second parent. Finally, it concatenates
these entries to form a child vector.</p>
</li>
<li><dl class="first docutils">
<dt><cite>two_points</cite>: it selects two random integers m and n between 1 and</dt>
<dd><p class="first last">ndimensions. The function selects vector entries numbered less than
or equal to m from the first parent. Then it selects vector entries
numbered from m + 1 to n, inclusive, from the second parent. Then
it selects vector entries numbered greater than n from the first
parent. The algorithm then concatenates these genes to form
a single gene.</p>
</dd>
</dl>
</li>
<li><p class="first"><cite>heuristic</cite>: returns a child that lies on the line containing the two
parents, a small distance away from the parent with the better
fitness value in the direction away from the parent with the worse
fitness value. You can specify how far the child is from the
better parent by the parameter <tt class="docutils literal"><span class="pre">ratio_xover</span></tt>
(which is 0.5 by default)</p>
</li>
<li><p class="first"><cite>linear_combination</cite>: creates children that are linear combinations
of the two parents with  the parameter <tt class="docutils literal"><span class="pre">ratio_xover</span></tt>
(which is 0.5 by default and should be between 0 and 1):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">child</span> <span class="o">=</span> <span class="n">parent1</span> <span class="o">+</span> <span class="n">Ratio</span> <span class="o">*</span> <span class="p">(</span> <span class="n">parent2</span> <span class="o">-</span> <span class="n">parent1</span><span class="p">)</span>
</pre></div>
</div>
<p>For  <tt class="docutils literal"><span class="pre">ratio_xover</span> <span class="pre">=</span> <span class="pre">0.5</span></tt> every child is an arithmetic mean of
two parents.</p>
</li>
</ul>
</blockquote>
<p><tt class="docutils literal"><span class="pre">func_mutation</span> <span class="pre">=</span> <span class="pre">'gaussian'</span></tt></p>
<blockquote>
<p>This function define how the genetic algorithm makes small random
changes in the individuals in the population to create mutation
children. Mutation provides genetic diversity and enable the genetic
algorithm to search a broader space. Different options are available:</p>
<ul>
<li><p class="first"><cite>gaussian</cite>: adds a random number taken from a Gaussian distribution
with mean 0 to each entry of the parent vector.</p>
<p>The &#8216;scale_mutation&#8217; parameter (0.8 by default) determines the
standard deviation at the first generation by
<tt class="docutils literal"><span class="pre">scale_mutation</span> <span class="pre">*</span> <span class="pre">(Xmax</span> <span class="pre">-</span> <span class="pre">Xmin)</span></tt> where
Xmax and Xmin are the boundaries.</p>
<p>The &#8216;shrink_mutation&#8217; parameter (0.2 by default) controls how the
standard deviation shrinks as generations go by:</p>
<div class="highlight-python"><pre>:math:`sigma_{i} = \sigma_{i-1}(1-shrink_{mutation} * i/maxiter)`
at iteration i.</pre>
</div>
</li>
<li><p class="first"><cite>uniform</cite>: The algorithm selects a fraction of the vector entries of
an individual for mutation, where each entry has a probability
<tt class="docutils literal"><span class="pre">mutation_rate</span></tt> (default is 0.1) of being mutated. In the second
step, the algorithm replaces each selected entry by a random number
selected uniformly from the range for that entry.</p>
</li>
</ul>
</blockquote>
</dd></dl>

<dl class="class">
<dt id="playdoh.OptimizationRun">
<em class="property">class </em><tt class="descclassname">playdoh.</tt><tt class="descname">OptimizationRun</tt><a class="headerlink" href="#playdoh.OptimizationRun" title="Permalink to this definition">¶</a></dt>
<dd><p>Contains information about a parallel optimization that has been launched
with the <tt class="docutils literal"><span class="pre">minimize_async</span></tt> or <tt class="docutils literal"><span class="pre">maximize_async</span></tt> function.</p>
<p>Methods:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">get_info()</span></tt></dt>
<dd>Return information about the current optimization asynchronously.</dd>
<dt><tt class="docutils literal"><span class="pre">get_result()</span></tt></dt>
<dd>Return the result as an <a class="reference internal" href="#playdoh.OptimizationResult" title="playdoh.OptimizationResult"><tt class="xref py py-class docutils literal"><span class="pre">OptimizationResult</span></tt></a> instance.
Block until the optimization has finished.</dd>
</dl>
</dd></dl>

<dl class="class">
<dt id="playdoh.OptimizationResult">
<em class="property">class </em><tt class="descclassname">playdoh.</tt><tt class="descname">OptimizationResult</tt><a class="headerlink" href="#playdoh.OptimizationResult" title="Permalink to this definition">¶</a></dt>
<dd><p>Type of objects returned by optimization functions.</p>
<p>Attributes:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">best_pos</span></tt></dt>
<dd>Minimizing position found by the algorithm.
For array-like fitness functions,
it is a single vector if there is one group,
or a list of vectors.
For keyword-like fitness functions, it is a dictionary
where keys are parameter names and values are numeric values.
If there are several groups, it is a list of dictionaries.</dd>
<dt><tt class="docutils literal"><span class="pre">best_fit</span></tt></dt>
<dd>The value of the fitness function for the best positions.
It is a single value i there is one group, or it is a list
if there are several groups.</dd>
<dt><tt class="docutils literal"><span class="pre">info</span></tt></dt>
<dd>A dictionary containing various information
about the optimization.</dd>
</dl>
<p>Also, the following syntax is possible with an
<tt class="docutils literal"><span class="pre">OptimizationResult</span></tt> instance <tt class="docutils literal"><span class="pre">or</span></tt>. The <tt class="docutils literal"><span class="pre">key</span></tt> is either
an optimizing parameter name for keyword-like fitness functions,
or a dimension index for array-like fitness functions.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">or[key]</span></tt></dt>
<dd>it is the best <tt class="docutils literal"><span class="pre">key</span></tt> parameter found (single value),
or the list of the best parameters <tt class="docutils literal"><span class="pre">key</span></tt> found for all groups.</dd>
<dt><tt class="docutils literal"><span class="pre">or[i]</span></tt></dt>
<dd>where <tt class="docutils literal"><span class="pre">i</span></tt> is a group index. This object has attributes
<tt class="docutils literal"><span class="pre">best_pos</span></tt>, <tt class="docutils literal"><span class="pre">best_fit</span></tt>, <tt class="docutils literal"><span class="pre">info</span></tt> but only for group <tt class="docutils literal"><span class="pre">i</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">or[i][key]</span></tt></dt>
<dd>where <tt class="docutils literal"><span class="pre">i</span></tt> is a group index, is the same as <tt class="docutils literal"><span class="pre">or[i].best_pos[key]</span></tt>.</dd>
</dl>
</dd></dl>

<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#guide-optimization"><em>Optimization</em></a>.</p>
</div>
</div>
<div class="section" id="loosely-coupled-parallel-problems">
<span id="ref-loosely"></span><h3>Loosely coupled parallel problems<a class="headerlink" href="#loosely-coupled-parallel-problems" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt id="playdoh.start_task">
<tt class="descclassname">playdoh.</tt><tt class="descname">start_task</tt><big>(</big><big>)</big><a class="headerlink" href="#playdoh.start_task" title="Permalink to this definition">¶</a></dt>
<dd><p>Launches a parallel task across CPUs on one or several computers.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">task_class</span></tt></dt>
<dd>The class implementing the task, must derive from the base class
<tt class="docutils literal"><span class="pre">ParallelTask</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">task_id=None</span></tt></dt>
<dd>The name of this particular task run. It should be unique, by default
it is randomly
generated based on the date and time of the launch. It is used to
retrieve the results.</dd>
<dt><tt class="docutils literal"><span class="pre">topology=[]</span></tt></dt>
<dd>The network topology. It defines the list of tubes used by the task.
It is a list of tuples <tt class="docutils literal"><span class="pre">(tubename,</span> <span class="pre">source,</span> <span class="pre">target)</span></tt> where
<tt class="docutils literal"><span class="pre">tubename</span></tt> is the name of the tube, <tt class="docutils literal"><span class="pre">source</span></tt> is an integer
giving the
node index of the source, <tt class="docutils literal"><span class="pre">target</span></tt> is the node index of the target.
Node indices start at 0.</dd>
<dt><tt class="docutils literal"><span class="pre">cpu=None</span></tt></dt>
<dd>The total number of CPUs to use.</dd>
<dt><tt class="docutils literal"><span class="pre">gpu=None</span></tt></dt>
<dd>When using GPUs, the total number of GPUs to use.</dd>
<dt><tt class="docutils literal"><span class="pre">machines=[]</span></tt></dt>
<dd>The list of machine IP addresses to launch the task over.</dd>
<dt><tt class="docutils literal"><span class="pre">allocation=None</span></tt></dt>
<dd>The allocation object returned by the <tt class="docutils literal"><span class="pre">allocate</span></tt> function.</dd>
<dt><tt class="docutils literal"><span class="pre">codedependencies</span></tt></dt>
<dd>The list of module dependencies.</dd>
<dt><tt class="docutils literal"><span class="pre">shared_data={}</span></tt></dt>
<dd>Shared data.</dd>
<dt><tt class="docutils literal"><span class="pre">args=()</span></tt></dt>
<dd>The arguments to the <tt class="docutils literal"><span class="pre">initialize</span></tt> method of the task. Every argument
item
is a list with one element per node.</dd>
<dt><tt class="docutils literal"><span class="pre">kwds={}</span></tt></dt>
<dd>The keyword arguments to the <tt class="docutils literal"><span class="pre">initialize</span></tt> method of the task. Every
value is a list with one element per node.</dd>
</dl>
</dd></dl>

<dl class="class">
<dt id="playdoh.ParallelTask">
<em class="property">class </em><tt class="descclassname">playdoh.</tt><tt class="descname">ParallelTask</tt><a class="headerlink" href="#playdoh.ParallelTask" title="Permalink to this definition">¶</a></dt>
<dd><p>The base class from which any parallel task must derive.</p>
<p>Three methods must be implemented:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">initialize(self,</span> <span class="pre">*args,</span> <span class="pre">**kwds)</span></tt></dt>
<dd>Initialization function, with any arguments and keyword arguments,
which
are specified at runtime in the <a class="reference internal" href="#playdoh.start_task" title="playdoh.start_task"><tt class="xref py py-func docutils literal"><span class="pre">start_task()</span></tt></a> function.</dd>
<dt><tt class="docutils literal"><span class="pre">start(self)</span></tt></dt>
<dd>Start the task.</dd>
<dt><tt class="docutils literal"><span class="pre">get_result(self)</span></tt></dt>
<dd>Return the result.</dd>
</dl>
<p>One method can be implemented.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">get_info(self)</span></tt></dt>
<dd>Return information about the task. Can be called asynchronously at
any time
by the client, to obtain for example the current iteration number.</dd>
</dl>
<p>Two methods from the base class are available:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">push(self,</span> <span class="pre">name,</span> <span class="pre">data)</span></tt></dt>
<dd>Put some <tt class="docutils literal"><span class="pre">data</span></tt> into the tube <tt class="docutils literal"><span class="pre">name</span></tt>. Named tubes are
associated to a single source
and a single target. Only the source can call this method.
Note that several tubes in the network can have
the same name, but two tubes entering or exiting a given
node cannot have the same name.</dd>
<dt><tt class="docutils literal"><span class="pre">pop(self,</span> <span class="pre">name)</span></tt></dt>
<dd>Pop data in the tube <tt class="docutils literal"><span class="pre">name</span></tt>: return the first item in
the tube (FIFO queue) and remove it.
If the tube is empty, block until the source put some
data into it. The call to this method
is equivalent to a synchronisation barrier.</dd>
</dl>
<p>Finally, the following read-only attributes are available:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">self.index</span></tt></dt>
<dd>The index of the current node, between 0 and n-1 if there
are n nodes in the network.</dd>
<dt><tt class="docutils literal"><span class="pre">self.unitidx</span></tt></dt>
<dd>The index of the CPU or GPU on the machine running the
current node.</dd>
<dt><tt class="docutils literal"><span class="pre">self.shared_data</span></tt></dt>
<dd>The shared data dictionary (see <a class="reference internal" href="playdoh.html#shared-data"><em>Shared data</em></a>).</dd>
<dt><tt class="docutils literal"><span class="pre">self.unit_type</span></tt></dt>
<dd>The unit type on this node, <tt class="docutils literal"><span class="pre">'CPU'</span></tt> or <tt class="docutils literal"><span class="pre">'GPU'</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">self.tubes_in</span></tt></dt>
<dd>The list of the incoming tube names on the current node.</dd>
<dt><tt class="docutils literal"><span class="pre">self.tubes_out</span></tt></dt>
<dd>The list of the outcoming tube names on the current node.</dd>
</dl>
</dd></dl>

<dl class="class">
<dt id="playdoh.TaskRun">
<em class="property">class </em><tt class="descclassname">playdoh.</tt><tt class="descname">TaskRun</tt><a class="headerlink" href="#playdoh.TaskRun" title="Permalink to this definition">¶</a></dt>
<dd><p>Contains information about a parallel task that has been launched
by the <a class="reference internal" href="#playdoh.start_task" title="playdoh.start_task"><tt class="xref py py-func docutils literal"><span class="pre">start_task()</span></tt></a> function.</p>
<p>Methods:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">get_info()</span></tt></dt>
<dd>Returns information about the current run asynchronously.</dd>
<dt><tt class="docutils literal"><span class="pre">get_result()</span></tt></dt>
<dd>Returns the result. Blocks until the task has finished.</dd>
</dl>
</dd></dl>

<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#guide-loosely"><em>Loosely coupled parallel problems</em></a>.</p>
</div>
</div>
</div>
<div class="section" id="other-functions-and-classes">
<h2>Other functions and classes<a class="headerlink" href="#other-functions-and-classes" title="Permalink to this headline">¶</a></h2>
<p>This section details the usage of other Playdoh functions and classes.</p>
<div class="section" id="playdoh-server">
<span id="ref-machines"></span><h3>Playdoh Server<a class="headerlink" href="#playdoh-server" title="Permalink to this headline">¶</a></h3>
<dl class="function">
<dt id="playdoh.open_server">
<tt class="descclassname">playdoh.</tt><tt class="descname">open_server</tt><big>(</big><em>port=None</em>, <em>maxcpu=None</em>, <em>maxgpu=None</em><big>)</big><a class="headerlink" href="#playdoh.open_server" title="Permalink to this definition">¶</a></dt>
<dd><p>Start the Playdoh server.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">port=DEFAULT_PORT</span></tt></dt>
<dd>The port (integer) of the Playdoh server. The default is DEFAULT_PORT,
which is 2718.</dd>
<dt><tt class="docutils literal"><span class="pre">maxcpu=MAXCPU</span></tt></dt>
<dd>The total number of CPUs the Playdoh server can use. <tt class="docutils literal"><span class="pre">MAXCPU</span></tt> is the
total number of CPUs on the computer.</dd>
<dt><tt class="docutils literal"><span class="pre">maxgpu=MAXGPU</span></tt></dt>
<dd>The total number of GPUs the Playdoh server can use. <tt class="docutils literal"><span class="pre">MAXGPU</span></tt> is the
total number of GPUs on the computer, if PyCUDA is installed.</dd>
</dl>
</dd></dl>

<dl class="function">
<dt id="playdoh.close_servers">
<tt class="descclassname">playdoh.</tt><tt class="descname">close_servers</tt><big>(</big><big>)</big><a class="headerlink" href="#playdoh.close_servers" title="Permalink to this definition">¶</a></dt>
<dd><p>Close the specified Playdoh server(s) remotely.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">addresses</span></tt></dt>
<dd>The list of the Playdoh server addresses to shutdown.</dd>
</dl>
</dd></dl>

<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">User guide for <a class="reference internal" href="playdoh.html#guide-machines"><em>Using several computers</em></a>.</p>
</div>
</div>
<div class="section" id="resource-allocation">
<span id="ref-allocation"></span><h3>Resource allocation<a class="headerlink" href="#resource-allocation" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="playdoh.Allocation">
<em class="property">class </em><tt class="descclassname">playdoh.</tt><tt class="descname">Allocation</tt><big>(</big><em>servers=</em><span class="optional">[</span><span class="optional">]</span>, <em>total_units=None</em>, <em>unit_type='CPU'</em>, <em>cpu=None</em>, <em>gpu=None</em>, <em>allocation=None</em>, <em>local=None</em><big>)</big><a class="headerlink" href="#playdoh.Allocation" title="Permalink to this definition">¶</a></dt>
<dd><p>Contain information about resource allocation on remote machines.
Is returned by the <a class="reference internal" href="#playdoh.allocate" title="playdoh.allocate"><tt class="xref py py-func docutils literal"><span class="pre">allocate()</span></tt></a> function.</p>
<p>Attributes:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">self.total_units</span></tt></dt>
<dd>Total number of units.</dd>
<dt><tt class="docutils literal"><span class="pre">self.allocation</span></tt></dt>
<dd>Allocation dictionary, were keys are machine tuples (IP, port) and
values are the number
of resources allocated to the client.</dd>
</dl>
</dd></dl>

<dl class="function">
<dt id="playdoh.allocate">
<tt class="descclassname">playdoh.</tt><tt class="descname">allocate</tt><big>(</big><em>machines=</em><span class="optional">[</span><span class="optional">]</span>, <em>total_units=None</em>, <em>unit_type='CPU'</em>, <em>allocation=None</em>, <em>local=None</em>, <em>cpu=None</em>, <em>gpu=None</em><big>)</big><a class="headerlink" href="#playdoh.allocate" title="Permalink to this definition">¶</a></dt>
<dd><p>Automatically allocate resources on different machines using available
resources.
Return an <a class="reference internal" href="#playdoh.Allocation" title="playdoh.Allocation"><tt class="xref py py-class docutils literal"><span class="pre">Allocation</span></tt></a> object which can be passed to Playdoh
functions like <a class="reference internal" href="#playdoh.map" title="playdoh.map"><tt class="xref py py-func docutils literal"><span class="pre">map()</span></tt></a>,
<a class="reference internal" href="#playdoh.minimize" title="playdoh.minimize"><tt class="xref py py-func docutils literal"><span class="pre">minimize()</span></tt></a>, etc.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">machines=[]</span></tt></dt>
<dd>The list of machines to use, as a list of strings (IP addresses)
or tuples
(IP address and port number).</dd>
<dt><tt class="docutils literal"><span class="pre">cpu=None</span></tt></dt>
<dd>The total number of CPUs to use.</dd>
<dt><tt class="docutils literal"><span class="pre">gpu=None</span></tt></dt>
<dd>The total number of GPUs to use.</dd>
<dt><tt class="docutils literal"><span class="pre">allocation=None</span></tt></dt>
<dd>This argument is specified when using manual resource allocation.
In this case,
<tt class="docutils literal"><span class="pre">allocation</span></tt> must be a dictionary with machine IP addresses as
keys and
resource number as values. The unit type must also be specified.</dd>
<dt><tt class="docutils literal"><span class="pre">unit_type='CPU'</span></tt></dt>
<dd>With manual resource allocation, specify the unit type: <tt class="docutils literal"><span class="pre">CPU</span></tt>
or <tt class="docutils literal"><span class="pre">GPU</span></tt>.</dd>
</dl>
</dd></dl>

<dl class="function">
<dt id="playdoh.get_server_resources">
<tt class="descclassname">playdoh.</tt><tt class="descname">get_server_resources</tt><big>(</big><em>servers</em><big>)</big><a class="headerlink" href="#playdoh.get_server_resources" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the complete resource allocation on the specified servers.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">servers</span></tt></dt>
<dd>The list of the servers. Every item is a string with the IP address of
the server, or a tuple <tt class="docutils literal"><span class="pre">(IP,</span> <span class="pre">port)</span></tt>.</dd>
</dl>
<p>Return an object <tt class="docutils literal"><span class="pre">resources</span></tt>, which is a list of dictionaries that can be
used like this:
<tt class="docutils literal"><span class="pre">nbr</span> <span class="pre">=</span> <span class="pre">resources[serverindex][type][client]</span></tt>, where:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">serverindex</span></tt> is the index of the server in the <tt class="docutils literal"><span class="pre">servers</span></tt> argument,</li>
<li><tt class="docutils literal"><span class="pre">type</span> <span class="pre">is</span> <span class="pre">``'CPU'</span></tt> or <tt class="docutils literal"><span class="pre">'GPU'</span></tt>,</li>
<li><tt class="docutils literal"><span class="pre">client</span></tt> is the IP address of the client, or <tt class="docutils literal"><span class="pre">ME</span></tt> if it corresponds
to this client,
i.e. the computer which made the call to <tt class="docutils literal"><span class="pre">get_server_resources</span></tt>,</li>
<li><tt class="docutils literal"><span class="pre">nbr</span></tt> is the number of <tt class="docutils literal"><span class="pre">type``(s)</span> <span class="pre">allocated</span> <span class="pre">to</span> <span class="pre">``client</span></tt> on server
<tt class="docutils literal"><span class="pre">serverindex</span></tt>.</li>
</ul>
</dd></dl>

<dl class="function">
<dt id="playdoh.get_my_resources">
<tt class="descclassname">playdoh.</tt><tt class="descname">get_my_resources</tt><big>(</big><em>servers</em><big>)</big><a class="headerlink" href="#playdoh.get_my_resources" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the resources allocated to this client on the specified servers.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">servers</span></tt></dt>
<dd>The list of the servers. Every item is a string with the IP address
of the server,
or a tuple <tt class="docutils literal"><span class="pre">(IP,</span> <span class="pre">port)</span></tt>.</dd>
</dl>
<p>Return an object <tt class="docutils literal"><span class="pre">resources</span></tt>, which is a dictionary where keys are
<tt class="docutils literal"><span class="pre">'CPU'</span></tt> or <tt class="docutils literal"><span class="pre">'GPU'</span></tt>,
and values are the number of allocated resources for this client.</p>
</dd></dl>

<dl class="function">
<dt id="playdoh.get_available_resources">
<tt class="descclassname">playdoh.</tt><tt class="descname">get_available_resources</tt><big>(</big><em>servers</em><big>)</big><a class="headerlink" href="#playdoh.get_available_resources" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the total number of (potentially) available resources for this client
on the specified servers, i.e. the number of idle resources (allocated
to no one)
plus the resources already allocated to this client.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">servers</span></tt></dt>
<dd>The list of the servers. Every item is a string with the IP address of
the server,
or a tuple <tt class="docutils literal"><span class="pre">(IP,</span> <span class="pre">port)</span></tt>.</dd>
</dl>
<p>Return an object <tt class="docutils literal"><span class="pre">resources</span></tt>, which is a dictionary where keys are
<tt class="docutils literal"><span class="pre">'CPU'</span></tt> or <tt class="docutils literal"><span class="pre">'GPU'</span></tt>,
and values are the number of idle resources for this client.</p>
</dd></dl>

<dl class="function">
<dt id="playdoh.request_resources">
<tt class="descclassname">playdoh.</tt><tt class="descname">request_resources</tt><big>(</big><em>servers</em>, <em>**resources</em><big>)</big><a class="headerlink" href="#playdoh.request_resources" title="Permalink to this definition">¶</a></dt>
<dd><p>Allocate resources for this client on the specified servers.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">servers</span></tt></dt>
<dd>The list of the servers. Every item is a string with the IP address
of the server,
or a tuple <tt class="docutils literal"><span class="pre">(IP,</span> <span class="pre">port)</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">**resources</span></tt></dt>
<dd>A dictionary where keys are <tt class="docutils literal"><span class="pre">'CPU'`</span> <span class="pre">or</span> <span class="pre">``'GPU'</span></tt> and values are lists
with the number of
CPUs or GPUs to allocate on each server.</dd>
</dl>
<p>Example: <tt class="docutils literal"><span class="pre">request_resources('bobs-machine.university.com',</span> <span class="pre">CPU=2)</span></tt></p>
</dd></dl>

<dl class="function">
<dt id="playdoh.request_all_resources">
<tt class="descclassname">playdoh.</tt><tt class="descname">request_all_resources</tt><big>(</big><em>servers</em>, <em>type</em>, <em>skip=</em><span class="optional">[</span><span class="optional">]</span>, <em>units=None</em><big>)</big><a class="headerlink" href="#playdoh.request_all_resources" title="Permalink to this definition">¶</a></dt>
<dd><p>Allocate resources optimally for this client on the specified servers, i.e.
as many resources as possible.</p>
<p>Arguments:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">servers</span></tt></dt>
<dd>The list of the servers. Every item is a string with the IP address of
the server,
or a tuple <tt class="docutils literal"><span class="pre">(IP,</span> <span class="pre">port)</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">type</span></tt></dt>
<dd>The unit type: <tt class="docutils literal"><span class="pre">'CPU'`</span> <span class="pre">or</span> <span class="pre">``'GPU'</span></tt>.</dd>
</dl>
<p>Return a list with the number of resources that just have been allocated
for every server.</p>
<p>Example: <tt class="docutils literal"><span class="pre">n</span> <span class="pre">=</span> <span class="pre">request_all_resources('bobs-machine.university.com',</span>
<span class="pre">type='CPU')[0]</span></tt></p>
</dd></dl>

<dl class="function">
<dt id="playdoh.get_total_resources">
<tt class="descclassname">playdoh.</tt><tt class="descname">get_total_resources</tt><big>(</big><em>servers</em><big>)</big><a class="headerlink" href="#playdoh.get_total_resources" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the total number of resources available to the clients on the given
server.
It is a dict resources[type]=nbr</p>
</dd></dl>

<dl class="function">
<dt id="playdoh.set_total_resources">
<tt class="descclassname">playdoh.</tt><tt class="descname">set_total_resources</tt><big>(</big><em>server</em>, <em>**resources</em><big>)</big><a class="headerlink" href="#playdoh.set_total_resources" title="Permalink to this definition">¶</a></dt>
<dd><p>Specify the total number of resources available on the given server</p>
</dd></dl>

<dl class="function">
<dt id="playdoh.get_gpu_count">
<tt class="descclassname">playdoh.</tt><tt class="descname">get_gpu_count</tt><big>(</big><big>)</big><a class="headerlink" href="#playdoh.get_gpu_count" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the total number of GPUs without initializing PyCUDA on the
current process.</p>
</dd></dl>

</div>
<div class="section" id="command-line-tool">
<span id="ref-commandline"></span><h3>Command line tool<a class="headerlink" href="#command-line-tool" title="Permalink to this headline">¶</a></h3>
<p>Playdoh includes a command-line tool which is automatically installed on your system
when you install Playdoh. On both Unix and Windows systems, you should be able
to directly use this tool with the command <tt class="docutils literal"><span class="pre">playdoh</span></tt>.
This tool allows you to open a server, close a server remotely, obtain the available
resources on distant servers and allocate resources.</p>
<p>Here are a few usage examples</p>
<div class="highlight-python"><pre># open the server with all possible resources
playdoh open

# open the server with 4 CPUs and 1 GPU
playdoh open 4 CPU 1 GPU

# change the total number of resources available on this machine
playdoh set 2 CPUs 0 GPU

# show the available resources/all resources on the given server
playdoh get bobs-machine.university.com [all]

# request 2 CPUs and 1 GPU on the server
playdoh request bobs-machine.university.com 2 CPUs 1 GPU

# request all resources on the server
playdoh request bobs-machine.university.com all CPUs all GPUs

# close the server on this machine
playdoh close

# close a server remotely
playdoh close bobs-machine.university.com</pre>
</div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper">
            <p class="logo"><a href="index.html">
              <img class="logo" src="_static/logo.png" alt="Logo"/>
            </a></p>
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Playdoh Reference</a><ul>
<li><a class="reference internal" href="#main-functions-and-classes">Main functions and classes</a><ul>
<li><a class="reference internal" href="#independent-parallel-problems">Independent parallel problems</a></li>
<li><a class="reference internal" href="#optimization">Optimization</a></li>
<li><a class="reference internal" href="#loosely-coupled-parallel-problems">Loosely coupled parallel problems</a></li>
</ul>
</li>
<li><a class="reference internal" href="#other-functions-and-classes">Other functions and classes</a><ul>
<li><a class="reference internal" href="#playdoh-server">Playdoh Server</a></li>
<li><a class="reference internal" href="#resource-allocation">Resource allocation</a></li>
<li><a class="reference internal" href="#command-line-tool">Command line tool</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="examples-resources.html"
                        title="previous chapter">Example: resources</a></p>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/reference.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" size="18" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             >index</a></li>
        <li class="right" >
          <a href="examples-resources.html" title="Example: resources"
             >previous</a> |</li>
        <li><a href="index.html">Playdoh v0.3.1 documentation</a> &raquo;</li> 
      </ul>
    </div>

    <div class="footer">
        &copy; Copyright 2011, Cyrille Rossant, Bertrand Fontaine, Dan Goodman.
      Last updated on Aug 17, 2011.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.6.
    </div>
<script type="text/javascript">

  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-6773961-3']);
  _gaq.push(['_trackPageview']);

  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();

</script>

  </body>
</html>